All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.sun.java.swing.tree.DefaultMutableTreeNode

java.lang.Object
   |
   +----com.sun.java.swing.tree.DefaultMutableTreeNode

public class DefaultMutableTreeNode
extends Object
implements Cloneable, MutableTreeNode, Serializable

A DefaultMutableTreeNode is a general-purpose node in a tree data structure. A tree node may have at most one parent and 0 or more children. DefaultMutableTreeNode provides operations for examining and modifying a node's parent and children and also operations for examining the tree that the node is a part of. A node's tree is the set of all nodes that can be reached by starting at the node and following all the possible links to parents and children. A node with no parent is the root of its tree; a node with no children is a leaf. A tree may consist of many subtrees, each node acting as the root for its own subtree.

This class provides enumerations for efficiently traversing a tree or subtree in various orders or for following the path between two nodes. A DefaultMutableTreeNode may also hold a reference to a user object, the use of which is left to the user. Asking a DefaultMutableTreeNode for its string representation with toString() returns the string representation of its user object.

This is not a thread safe class.If you intend to use a DefaultMutableTreeNode (or a tree of TreeNodes) in more than one thread, you need to do your own synchronizing. A good convention to adopt is synchronizing on the root node of a tree.

While DefaultMutableTreeNode implements the MutableTreeNode interface and will allow you to add in any implementation of MutableTreeNode not all of the methods in DefaultMutableTreeNode will be applicable to all MutableTreeNodes implementations. Especially with some of the enumerations that are provided, using some of these methods assumes the DefaultMutableTreeNode contains only DefaultMutableNode instances. All of the TreeNode/MutableTreeNode methods will behave as defined no matter what implementations are added.

Warning: serialized objects of this class will not be compatible with future swing releases. The current serialization support is appropriate for short term storage or RMI between Swing1.0 applications. It will not be possible to load serialized Swing1.0 objects with future releases of Swing. The JDK1.2 release of Swing will be the compatibility baseline for the serialized form of Swing objects.

See Also:: MutableTreeNode

allowsChildren: true if the node is able to have children
children: array of children, may be null if this node has no children
EMPTY_ENUMERATION: A null-enumeration class returned when an enumeration of a leaf node's children is requested.
parent: this node's parent, or null if this node has no parent
userObject: optional user object

DefaultMutableTreeNode(): Creates a tree node that has no parent and no children, but which allows children.
DefaultMutableTreeNode(Object): Creates a tree node with no parent, no children, but which allows children, and initializes it with the specified user object.
DefaultMutableTreeNode(Object, boolean): Creates a tree node with no parent, no children, initialized with the specified user object, and that allows children only if specified.

add(MutableTreeNode): Removes newChild from its parent and makes it a child of this node by adding it to the end of this node's child array.
breadthFirstEnumeration(): Creates and returns an enumeration that traverses the subtree rooted at this node in breadth-first order.
children(): Creates and returns a forward-order enumeration of this node's children.
clone(): Overridden to make clone public.
depthFirstEnumeration(): Creates and returns an enumeration that traverses the subtree rooted at this node in depth-first order.
getAllowsChildren(): Returns true if this node is allowed to have children.
getChildAfter(TreeNode): Returns the child in this node's child array that immediately follows aChild, which must be a child of this node.
getChildAt(int): Returns the child at the specified index in this node's child array.
getChildBefore(TreeNode): Returns the child in this node's child array that immediately precedes aChild, which must be a child of this node.
getChildCount(): Returns the number of children of this node.
getDepth(): Returns the depth of the tree rooted at this node -- the longest distance from this node to a leaf.
getFirstChild(): Returns this node's first child.
getFirstLeaf(): Finds and returns the first leaf that is a descendant of this node -- either this node or its first child's first leaf.
getIndex(TreeNode): Returns the index of the specified child in this node's child array.
getLastChild(): Returns this node's last child.
getLastLeaf(): Finds and returns the last leaf that is a descendant of this node -- either this node or its last child's last leaf.
getLeafCount(): Returns the total number of leaves that are descendants of this node.
getLevel(): Returns the number of levels above this node -- the distance from the root to this node.
getNextLeaf(): Returns the leaf after this node or null if this node is the last leaf in the tree.
getNextNode(): Returns the node that follows this node in a preorder traversal of this node's tree.
getNextSibling(): Returns the next sibling of this node in the parent's children array.
getParent(): Returns this node's parent or null if this node has no parent.
getPath(): Returns the path from the root, to get to this node.
getPathToRoot(TreeNode, int): Builds the parents of node up to and including the root node, where the original node is the last element in the returned array.
getPreviousLeaf(): Returns the leaf before this node or null if this node is the first leaf in the tree.
getPreviousNode(): Returns the node that precedes this node in a preorder traversal of this node's tree.
getPreviousSibling(): Returns the previous sibling of this node in the parent's children array.
getRoot(): Returns the root of the tree that contains this node.
getSharedAncestor(DefaultMutableTreeNode): Returns the nearest common ancestor to this node and aNode.
getSiblingCount(): Returns the number of siblings of this node.
getUserObject(): Returns this node's user object.
getUserObjectPath(): Returns the user object path, from the root, to get to this node.
insert(MutableTreeNode, int): Removes newChild from its present parent (if it has a parent), sets the child's parent to this node, and then adds the child to this node's child array at index childIndex.
isLeaf(): Returns true if this node has no children.
isNodeAncestor(TreeNode): Returns true if anotherNode is an ancestor of this node -- if it is this node, this node's parent, or an ancestor of this node's parent.
isNodeChild(TreeNode): Returns true if aNode is a child of this node.
isNodeDescendant(DefaultMutableTreeNode): Returns true if anotherNode is a descendant of this node -- if it is this node, one of this node's children, or a descendant of one of this node's children.
isNodeRelated(DefaultMutableTreeNode): Returns true if and only if aNode is in the same tree as this node.
isNodeSibling(TreeNode): Returns true if anotherNode is a sibling of (has the same parent as) this node.
isRoot(): Returns true if this node is the root of the tree.
pathFromAncestorEnumeration(TreeNode): Creates and returns an enumeration that follows the path from ancestor to this node.
postorderEnumeration(): Creates and returns an enumeration that traverses the subtree rooted at this node in postorder.
preorderEnumeration(): Creates and returns an enumeration that traverses the subtree rooted at this node in preorder.
remove(int): Removes the child at the specified index from this node's children and sets that node's parent to null.
remove(MutableTreeNode): Removes aChild from this node's child array, giving it a null parent.
removeAllChildren(): Removes all of this node's children, setting their parents to null.
removeFromParent(): Removes the subtree rooted at this node from the tree, giving this node a null parent.
setAllowsChildren(boolean): Determines whether or not this node is allowed to have children.
setParent(MutableTreeNode): Sets this node's parent to newParent but does not change the parent's child array.
setUserObject(Object): Sets the user object for this node to userObject.
toString(): Returns the result of sending toString() to this node's user object, or null if this node has no user object.

EMPTY_ENUMERATION

 public static final Enumeration EMPTY_ENUMERATION

A null-enumeration class returned when an enumeration of a leaf node's children is requested.

parent

 protected MutableTreeNode parent

this node's parent, or null if this node has no parent

children

 protected Vector children

array of children, may be null if this node has no children

userObject

 protected transient Object userObject

optional user object

allowsChildren

 protected boolean allowsChildren

true if the node is able to have children

DefaultMutableTreeNode

 public DefaultMutableTreeNode()

Creates a tree node that has no parent and no children, but which allows children.

DefaultMutableTreeNode

 public DefaultMutableTreeNode(Object userObject)

Creates a tree node with no parent, no children, but which allows children, and initializes it with the specified user object.

Parameters:: userObject - an Object provided by the user that constitutes the node's data

DefaultMutableTreeNode

 public DefaultMutableTreeNode(Object userObject,
                               boolean allowsChildren)

Creates a tree node with no parent, no children, initialized with the specified user object, and that allows children only if specified.

Parameters:: userObject - an Object provided by the user that constitutes the node's data; allowsChildren - if true, the node is allowed to have child nodes -- otherwise, it is always a leaf node

insert

 public void insert(MutableTreeNode newChild,
                    int childIndex)

Removes newChild from its present parent (if it has a parent), sets the child's parent to this node, and then adds the child to this node's child array at index childIndex. newChild must not be null and must not be an ancestor of this node.

Parameters:: newChild - the MutableTreeNode to insert under this node; childIndex - the index in this node's child array where this node is to be inserted
Throws: ArrayIndexOutOfBoundsException: if childIndex is out of bounds
Throws: IllegalArgumentException: if newChild is null or is an ancestor of this node
Throws: IllegalStateException: if this node does not allow children
See Also:: isNodeDescendant

remove

 public void remove(int childIndex)

Removes the child at the specified index from this node's children and sets that node's parent to null. The child node to remove must be a MutableTreeNode.

Parameters:: childIndex - the index in this node's child array of the child to remove
Throws: ArrayIndexOutOfBoundsException: if childIndex is out of bounds

setParent

 public void setParent(MutableTreeNode newParent)

Sets this node's parent to newParent but does not change the parent's child array. This method is called from insert() and remove() to reassign a child's parent, it should not be messaged from anywhere else.

Parameters:: newParent - this node's new parent

getParent

 public TreeNode getParent()

Returns this node's parent or null if this node has no parent.

Returns:: this node's parent TreeNode, or null if this node has no parent

getChildAt

 public TreeNode getChildAt(int index)

Returns the child at the specified index in this node's child array.

Parameters:: index - an index into this node's child array
Returns:: the TreeNode in this node's child array at the specified index
Throws: ArrayIndexOutOfBoundsException: if index is out of bounds

getChildCount

 public int getChildCount()

Returns the number of children of this node.

Returns:: an int giving the number of children of this node

getIndex

 public int getIndex(TreeNode aChild)

Returns the index of the specified child in this node's child array. If the specified node is not a child of this node, returns -1. This method performs a linear search and is O(n) where n is the number of children.

Parameters:: aChild - the TreeNode to search for among this node's children
Returns:: an int giving the index of the node in this node's child array, or -1 if the specified node is a not a child of this node
Throws: IllegalArgumentException: if aChild is null

children

 public Enumeration children()

Creates and returns a forward-order enumeration of this node's children. Modifying this node's child array invalidates any child enumerations created before the modification.

Returns:: an Enumeration of this node's children

setAllowsChildren

 public void setAllowsChildren(boolean allows)

Determines whether or not this node is allowed to have children. If allows is false, all of this node's children are removed.

Note: By default, a node allows children.

Parameters:: allows - true if this node is allowed to have children

getAllowsChildren

 public boolean getAllowsChildren()

Returns true if this node is allowed to have children.

Returns:: true if this node allows children, else false

setUserObject

 public void setUserObject(Object userObject)

Sets the user object for this node to userObject.

Parameters:: userObject - the Object that constitutes this node's user-specified data
See Also:: getUserObject, toString

getUserObject

 public Object getUserObject()

Returns this node's user object.

Returns:: the Object stored at this node by the user
See Also:: setUserObject, toString

removeFromParent

 public void removeFromParent()

Removes the subtree rooted at this node from the tree, giving this node a null parent. Does nothing if this node is the root of its tree.

remove

 public void remove(MutableTreeNode aChild)

Removes aChild from this node's child array, giving it a null parent.

Parameters:: aChild - a child of this node to remove
Throws: IllegalArgumentException: if aChild is null or is not a child of this node

removeAllChildren

 public void removeAllChildren()

Removes all of this node's children, setting their parents to null. If this node has no children, this method does nothing.

add

 public void add(MutableTreeNode newChild)

Removes newChild from its parent and makes it a child of this node by adding it to the end of this node's child array.

Parameters:: newChild - node to add as a child of this node
Throws: IllegalArgumentException: if newChild is null
Throws: IllegalStateException: if this node does not allow children
See Also:: insert

isNodeAncestor

 public boolean isNodeAncestor(TreeNode anotherNode)

Returns true if anotherNode is an ancestor of this node -- if it is this node, this node's parent, or an ancestor of this node's parent. (Note that a node is considered an ancestor of itself.) If anotherNode is null, this method returns false. This operation is at worst O(h) where h is the distance from the root to this node.

Parameters:: anotherNode - node to test as an ancestor of this node
Returns:: true if this node is a descendant of anotherNode
See Also:: isNodeDescendant, getSharedAncestor

isNodeDescendant

 public boolean isNodeDescendant(DefaultMutableTreeNode anotherNode)

Returns true if anotherNode is a descendant of this node -- if it is this node, one of this node's children, or a descendant of one of this node's children. Note that a node is considered a descendant of itself. If anotherNode is null, returns false. This operation is at worst O(h) where h is the distance from the root to anotherNode.

Parameters:: anotherNode - node to test as descendant of this node
Returns:: true if this node is an ancestor of anotherNode
See Also:: isNodeAncestor, getSharedAncestor

getSharedAncestor

 public TreeNode getSharedAncestor(DefaultMutableTreeNode aNode)

Returns the nearest common ancestor to this node and aNode. Returns null, if no such ancestor exists -- if this node and aNode are in different trees or if aNode is null. A node is considered an ancestor of itself.

Parameters:: aNode - node to find common ancestor with
Returns:: nearest ancestor common to this node and aNode, or null if none
See Also:: isNodeAncestor, isNodeDescendant

isNodeRelated

 public boolean isNodeRelated(DefaultMutableTreeNode aNode)

Returns true if and only if aNode is in the same tree as this node. Returns false if aNode is null.

Returns:: true if aNode is in the same tree as this node; false if aNode is null
See Also:: getSharedAncestor, getRoot

getDepth

 public int getDepth()

Returns the depth of the tree rooted at this node -- the longest distance from this node to a leaf. If this node has no children, returns 0. This operation is much more expensive than getLevel() because it must effectively traverse the entire tree rooted at this node.

Returns:: the depth of the tree whose root is this node
See Also:: getLevel

getLevel

 public int getLevel()

Returns the number of levels above this node -- the distance from the root to this node. If this node is the root, returns 0.

Returns:: the number of levels above this node
See Also:: getDepth

getPath

 public TreeNode[] getPath()

Returns the path from the root, to get to this node. The last element in the path is this node.

Returns:: an array of TreeNode objects giving the path, where the first element in the path is the root and the last element is this node.

getPathToRoot

 protected TreeNode[] getPathToRoot(TreeNode aNode,
                                    int depth)

Builds the parents of node up to and including the root node, where the original node is the last element in the returned array. The length of the returned array gives the node's depth in the tree.

Parameters:: aNode - the TreeNode to get the path for; depth - an int giving the number of steps already taken towards the root (on recursive calls), used to size the returned array
Returns:: an array of TreeNodes giving the path from the root to the specified node

getUserObjectPath

 public Object[] getUserObjectPath()

Returns the user object path, from the root, to get to this node. If some of the TreeNodes in the path have null user objects, the returned path will contain nulls.

getRoot

 public TreeNode getRoot()

Returns the root of the tree that contains this node. The root is the ancestor with a null parent.

Returns:: the root of the tree that contains this node
See Also:: isNodeAncestor

isRoot

 public boolean isRoot()

Returns true if this node is the root of the tree. The root is the only node in the tree with a null parent; every tree has exactly one root.

Returns:: true if this node is the root of its tree

getNextNode

 public DefaultMutableTreeNode getNextNode()

Returns the node that follows this node in a preorder traversal of this node's tree. Returns null if this node is the last node of the traversal. This is an inefficient way to traverse the entire tree; use an enumeration, instead.

Returns:: the node that follows this node in a preorder traversal, or null if this node is last
See Also:: preorderEnumeration

getPreviousNode

 public DefaultMutableTreeNode getPreviousNode()

Returns the node that precedes this node in a preorder traversal of this node's tree. Returns null if this node is the first node of the traveral -- the root of the tree. This is an inefficient way to traverse the entire tree; use an enumeration, instead.

Returns:: the node that precedes this node in a preorder traversal, or null if this node is the first
See Also:: preorderEnumeration

preorderEnumeration

 public Enumeration preorderEnumeration()

Creates and returns an enumeration that traverses the subtree rooted at this node in preorder. The first node returned by the enumeration's nextElement() method is this node.